<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta charset="UTF-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1"/>
  <title>bpkg-pkg-build(1) bpkg 0.17.0</title>

  <style type="text/css">
/* file      : common.css
 * license   : MIT; see accompanying LICENSE file
 */

html
{
  font-family: "Helvetica Neue", Helvetica, "Segoe UI", Arial, freesans, sans-serif;
  font-weight: normal;
  font-size: 18px;
  line-height: 1.4em;
  letter-spacing: 0.01em;

  color: #292929;
}

body {margin: 0;} /* There is non-0 default margin for body. */

/* See notes on what's going on here. */
body {min-width: 17em;}
@media only screen and (min-width: 360px)
{
  body {min-width: 19em;}
}

/*
 * Header (optional).
 */

#header-bar
{
  width: 100%;

  background: rgba(0, 0, 0, 0.04);
  border-bottom: 1px solid rgba(0, 0, 0, 0.2);

  padding: .4em 0 .42em 0;
  margin: 0 0 1.4em 0;
}

#header
{
  /* Same as in #content. */
  max-width: 41em;
  margin: 0 auto 0 auto;
  padding: 0 .4em 0 .4em;

  -webkit-box-sizing: border-box;
  -moz-box-sizing: border-box;
  box-sizing: border-box;

  width: 100%;
  display: table;
  border: none;
  border-collapse: collapse;
}

#header-logo, #header-menu
{
  display: table-cell;
  border: none;
  padding: 0;
  vertical-align: middle;
}

#header-logo {text-align: left;}
#header-menu {text-align: right;}

/* These overlap with #header's margin because of border collapsing. */
#header-logo {padding-left: .4em;}
#header-menu {padding-right: .4em;}

#header-logo a
{
  color: #000;
  text-decoration: none;
  outline: none;
}
#header-logo a:visited {color: #000;}
#header-logo a:hover, #header-logo a:active {color: #000;}

#header-menu a
{
  font-size: 0.889em;
  line-height: 1.4em;
  text-align: right;
  margin-left: 1.2em;
  white-space: nowrap;
  letter-spacing: 0;
}

#header-menu a
{
  color: #000;
  outline: none;
}
#header-menu a:visited {color: #000;}
#header-menu a:hover, #header-menu a:active
{
  color: #3870c0;
  text-decoration: none;
}

/* Flexbox-based improvements though the above works reasonably well. */
#header-menu-body
{
  width: 100%;

  display: -webkit-inline-flex;
  display: inline-flex;

  -webkit-flex-flow: row wrap;
  flex-flow: row wrap;

  -webkit-justify-content: flex-end;
  justify-content: flex-end;
}

/* Whether we want it (and at which point) depends on the size of the menu. */
/*
@media only screen and (max-width: 567px)
{
  #header-menu-body
  {
    -webkit-flex-direction: column;
    flex-direction: column;
  }
}
*/

/*
 * Content.
 */

#content
{
  max-width: 41em;
  margin: 0 auto 0 auto;
  padding: 0 .4em 0 .4em; /* Space between text and browser frame. */

  -webkit-box-sizing: border-box;
  -moz-box-sizing: border-box;
  box-sizing: border-box;
}

/*
 * Footer (optional).
 */

#footer
{
  color: #767676;
  font-size: 0.7223em;
  line-height: 1.3em;
  margin: 2.2em 0 1em 0;
  text-align: center;
}

#footer a
{
  color: #767676;
  text-decoration: underline;
}
#footer a:visited {color: #767676;}
#footer a:hover, #footer a:active {color: #3870c0;}

/* Screen size indicator in the footer. The before/after content is in case
   we don't have any content in the footer. Margin is to actually see the
   border separate from the browser frame. */

/*
#footer:before {content: "\A0";}
#footer:after {content: "\A0";}

#footer
{
  border-left: 1px solid;
  border-right: 1px solid;
  margin-left: 1px;
  margin-right: 1px;
}

@media only screen and (max-width: 359px)
{
  #footer {border-color: red;}
}

@media only screen and (min-width: 360px) and (max-width: 567px)
{
  #footer {border-color: orange;}
}

@media only screen and (min-width: 568px) and (max-width: 1023px)
{
  #footer {border-color: blue;}
}

@media only screen and (min-width: 1024px)
{
  #footer {border-color: green;}
}
*/

/*
 * Common elements.
 */

p, li, dd {text-align: justify;}
.code {text-align: left;} /* Manually aligned. */
pre {text-align: left;}   /* If it is inside li/dd. */

/* Notes. */

.note
{
  color: #606060;
}

div.note
{
  margin: 2em 0 2em 0; /* The same top/bottom margings as pre box. */

  padding-left: 0.5em;
  border: 0.25em;
  border-left-style: solid;
  border-color: #808080;

  page-break-inside: avoid;
}

div.note :first-child {margin-top:    0;}
div.note :last-child  {margin-bottom: 0;}

span.note::before {content: "[Note: "}
span.note::after  {content: "]"}

/* Links. */
a
{
  color: #3870c0;
  /*color: #4078c0;*/
  text-decoration: none;
}

a:hover, a:active
{
/*color: #006fbf;*/
/*color: #0087e7;*/
  text-decoration: underline;
}

a:visited
{
/*color: #003388;*/
  color: #00409c;
}

/* Standard paragraph. */

p, pre {margin: 1em 0 1em 0;}

/* Standard lists. */
ul, ol, dl {margin: 1em 0 1em 0;}
ul li, ol li {margin: 0 0 .4em 0;}
ul li {list-style-type: circle;}
dl dt {margin: 0 0 0 0;}
dl dd {margin: 0 0 .6em 1.8em;}

code, pre
{
  font-family: Consolas, "Liberation Mono", Menlo, Courier, monospace;
  font-size: 0.92em;
  letter-spacing: 0;
}

pre {white-space: pre-wrap;}
@media only screen and (max-width: 567px)
{
  pre {word-break: break-all;}
}

/* Use page rather than system font settings. */
input
{
  font-family: inherit;
  font-weight: inherit;
  font-size:   inherit;
  line-height: inherit;
}

/* file      : pre-box.css
 * license   : MIT; see accompanying LICENSE file
 */

/* Note: see also p-code-box.css. */

pre
{
  background-color: rgba(0, 0, 0, 0.05);
  border-radius: 0.2em;
  padding: .8em .4em .8em .4em;
  margin: 2em -.4em 2em -.4em; /* Use margins of #content. */
}

/* file      : man.css
 * license   : MIT; see accompanying LICENSE file
 */

/* Bases:
 *
 * common.css
 * pre-box.css
 *
 */

#content
{
  max-width: 42.1em;
  padding-left: 1.5em; /* Reserve for the heading. */
}

h1
{
  font-weight: normal;
  font-size: 1.58em;
  line-height: 1.4em;
  margin: 1.6em 0 .6em -.88em;
}

/* Definition list for options. */
dl.options dt {margin: 1em 0 0 0;}
dl.options dd {margin: .1em 0 0 4.5em;}

/* Make lists inside option descriptions a tad smaller. */
dl.options dd ul, dl.options dd ol, dl.options dd dl
{
  font-size: 0.889em;
  line-height: 1.4em;
}

  </style>

</head>
<body>
<div id="content">

  <h1>NAME</h1>

  <p><b><code>bpkg-pkg-build</code></b> &#8211; build package</p>
  <h1>SYNOPSIS</h1>

  <p class="code"><code><b>bpkg pkg-build</b>|<b>build</b> [<i>options</i>]
  [<b>--upgrade</b>|<b>-u</b> | <b>--patch</b>|<b>-p</b>]
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;[<i>cfg-var</i>...
  <b>--</b>] <i>pkg-spec</i>...
  <br/>
  <b>bpkg pkg-build</b>|<b>build</b> [<i>options</i>]
  &#160;<b>--upgrade</b>|<b>-u</b> | <b>--patch</b>|<b>-p</b>
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;[<i>cfg-var</i>...
  <b>--</b>]</code></p>

  <p class="code"><code><i>pkg-spec</i> =
  [<i>flags</i>](([<i>scheme</i><b>:</b>]<i>pkg</i>[<i>ver-spec</i>])<b>,</b>...[<b>@</b><i>rep-loc</i>]
  | 
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;[<b>@</b>]<i>rep-loc</i>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;|

  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>file</i>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;|

  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>dir</i><b>/</b>)
  <br/>
  <i>flags</i>&#160;&#160;&#160;&#160;&#160;&#160;= <b>?</b>
  <br/>
  <i>scheme</i> &#160;&#160;&#160;&#160;= <b>sys</b>
  <br/>
  <i>ver-spec</i>&#160;&#160;&#160;= <b>/</b><i>version</i> |
  <i>version-constraint</i></code></p>

  <h1>DESCRIPTION</h1>

  <p>The <code><b>pkg-build</b></code> command builds one or more packages
  including all their dependencies. Besides building new packages, this
  command is also used to upgrade or downgrade packages that are already
  present in the configuration. And unless the
  <code><b>--keep-unused</b>|<b>-K</b></code> option is specified,
  <code><b>pkg-build</b></code> will also drop dependency packages that would
  otherwise no longer be used.</p>

  <p>The first form (one or more packages are specified) builds new or
  upgrades (by default or if <code><b>--upgrade</b></code> is specified) or
  patches (if <code><b>--patch</b></code> is specified) the specified
  packages. The second form (no arguments but either
  <code><b>--upgrade</b></code> or <code><b>--patch</b></code> is specified)
  upgrades or patches all the held packages in the configuration (see below
  for details on held package).</p>

  <p>In both forms specifying the <code><b>--immediate</b>|<b>-i</b></code> or
  <code><b>--recursive</b>|<b>-r</b></code> option causes
  <code><b>pkg-build</b></code> to also upgrade or patch the immediate or all
  dependencies of the specified (first form) or held (second form) packages,
  respectively. Note also that in the first form these options can only be
  specified with an explicit <code><b>--upgrade</b></code> or
  <code><b>--patch</b></code>.</p>

  <p>Each package can be specified as just the name (<code><i>pkg</i></code>)
  with optional version specification (<code><i>ver-spec</i></code>), in which
  case the source code for the package will be automatically fetched from one
  of the configured repositories. See the <a
  href="bpkg-rep-add.xhtml"><code><b>bpkg-rep-add(1)</b></code></a> and <a
  href="bpkg-rep-fetch.xhtml"><code><b>bpkg-rep-fetch(1)</b></code></a>
  commands for more information on package repositories. The version
  specification (<code><i>ver-spec</i></code>) can be either the exact version
  in the <code><b>/</b><i>version</i></code> form or the version constraint as
  described in <a
  href="build2-package-manager-manual.xhtml#package-version-constraint">Package
  Version Constraint</a>. If <code><i>ver-spec</i></code> is not specified,
  then the latest available version will be built. To downgrade, the desired
  version must be specified explicitly. For example:</p>

  <pre>bpkg build foo libfoo/1.2.3 "bar &lt; 2.0.0"</pre>

  <p>Alternatively, the package repository location
  (<code><i>rep-loc</i></code>) can be specified as part of the build command.
  In this case, if <code><i>ver-spec</i></code> is not specified, then the
  latest available from this repository version will be built. For
  example:</p>

  <pre>bpkg build foo,libfoo/1.2.3@https://git.example.org/foo.git#master</pre>

  <p>If only the location is specified, then the latest versions of all the
  packages available directly from this repository will be built (note that
  this does not include packages available from complement repositories). The
  <code><b>@</b></code> delimiter can be omitted if the location is a URL. For
  example:</p>

  <pre>bpkg build https://git.example.org/foo.git#master
bpkg build @/path/to/repository/</pre>

  <p>A package name (<code><i>pkg</i></code>) can be prefixed with a package
  scheme (<code><i>scheme</i></code>). Currently the only recognized scheme is
  <code><b>sys</b></code> which instructs <code><b>pkg-build</b></code> to
  configure the package as available from the system rather than building it
  from source.</p>

  <p>The system package version (<code><i>ver-spec</i></code>) may not be a
  version constraint but may be the special '<code><b>/*</b></code>' value,
  which indicates that the version should be considered unknown but satisfying
  any version constraint. If unspecified, then <code><b>pkg-build</b></code>
  will attempt to query the system package manager for the installed version
  unless the system package manager is unsupported or this functionality is
  disabled with <code><b>--sys-no-query</b></code>, in which case the
  '<code><b>/*</b></code>' <code><i>ver-spec</i></code> is assumed. If the
  system package manager is supported, then the automatic installation of an
  available package can be requested with the
  <code><b>--sys-install</b></code> option. Note that if the version is not
  explicitly specified, then at least a stub package must be available from
  one of the repositories unless the <code><b>--sys-no-stub</b></code> option
  is specified.</p>

  <p>Finally, a package can be specified as either the path to the package
  archive (<code><i>file</i></code>) or to the package directory
  (<code><i>dir</i></code><code><b>/</b></code>; note that it must end with a
  directory separator). See the <a
  href="bpkg-pkg-fetch.xhtml"><code><b>bpkg-pkg-fetch(1)</b></code></a> and <a
  href="bpkg-pkg-unpack.xhtml"><code><b>bpkg-pkg-unpack(1)</b></code></a>
  commands for more information on the semantics of specifying the package as
  an archive or a directory.</p>

  <p>Additional configuration variables (<code><i>cfg-var</i></code>), if any,
  should be specified before packages (<code><i>pkg-spec</i></code>) and
  should be separated with <code><b>--</b></code>. Such variables are
  effective only when configuring and only for packages that were explicitly
  specified on the command line (unless global overrides). They can also be
  specified to only apply to specific packages using the argument grouping
  mechanism discussed below. See <a
  href="bpkg-pkg-configure.xhtml"><code><b>bpkg-pkg-configure(1)</b></code></a>
  for more information on configuration variables.</p>

  <p>By default a package that is specified explicitly on the command line is
  built to <i>hold</i>: it will not be considered for automatic removal if it
  no longer has any dependents. Only versions from repositories that were
  added to the configuration (<a
  href="bpkg-rep-add.xhtml"><code><b>bpkg-rep-add(1)</b></code></a>) are
  considered as available for build to hold.</p>

  <p>Alternatively, a package can be built (or, more commonly,
  upgraded/downgraded) as a <i>dependency</i> by specifying the
  <code><b>?</b></code> flag (<code><i>flags</i></code>) or the
  <code><b>--dependency</b></code> option. Such a package will only be added
  to the configuration if it actually has any dependents and once no longer
  used, it will be automatically dropped. Only versions from prerequisite
  repositories of dependent packages are considered as available for build as
  a dependency.</p>

  <p>Packages (both built to hold and as dependencies) that are specified with
  an explicit package version (<code><i>ver-spec</i></code>) or as an archive
  or directory, will have their versions held, that is, they will not be
  automatically upgraded.</p>

  <p>As an illustration, let's assume in the following example that the stable
  repository contains packages <code><b>foo</b></code>
  <code><b>1.0.0</b></code> as well as <code><b>libfoo</b></code>
  <code><b>1.0.0</b></code> and <code><b>1.1.0</b></code> while testing
  &#8211; <code><b>libfoo</b></code> <code><b>2.0.0</b></code>, that testing
  is complemented by stable, and that <code><b>foo</b></code> depends on
  <code><b>libfoo >= 1.0.0</b></code>:</p>

  <pre>bpkg fetch https://example.org/1/testing

bpkg build foo            # build foo    1.0.0 to hold
                          # build libfoo 1.1.0 as dependency

bpkg build ?libfoo/1.0.0  # downgrade libfoo 1.0.0 as dependency,
                          #           also hold version 1.0.0

bpkg build ?libfoo/2.0.0  # error: 2.0.0 unavailable in dependent's
                          #        (foo) repository (stable)

bpkg build libfoo/2.0.0   # upgrade libfoo 2.0.0 to hold,
                          #         also hold version 2.0.0</pre>

  <p>A package can be built in one of the linked configurations instead of the
  current (or host/build system module, for build-time dependencies)
  configuration by specifying one of the <code><b>--config-*</b></code>
  options (see <a
  href="bpkg-cfg-create.xhtml"><code><b>bpkg-cfg-create(1)</b></code></a> for
  background on linked configurations). For example:</p>

  <pre>bpkg build foo { --config-name=alt-host }+ ?bison</pre>

  <h1>PKG-BUILD PACKAGE OPTIONS</h1>

  <p>The following options (as well as additional configuration variables) can
  be grouped to apply to a specific <code><i>pkg-spec</i></code> as well as
  specified globally, in which case they apply to all the specified packages
  (see <a
  href="bpkg-argument-grouping.xhtml"><code><b>bpkg-argument-grouping(1)</b></code></a>
  for details).</p>

  <dl class="options">
    <dt><code><b>--upgrade</b></code>|<code><b>-u</b></code></dt>
    <dd>Upgrade packages to the latest available version that satisfies all
    the constraints.</dd>

    <dt><code><b>--patch</b></code>|<code><b>-p</b></code></dt>
    <dd>Upgrade packages to the latest available patch version that satisfies
    all the constraints.</dd>

    <dt><code><b>--deorphan</b></code></dt>
    <dd>Replace orphaned packages with the best matching available package
    versions which satisfy all the constraints.

    <p>It may happen that a built package no longer has the corresponding
    package available in the repository it came from (for example, as a result
    of <a
    href="bpkg-rep-fetch.xhtml"><code><b>bpkg-rep-fetch(1)</b></code></a> or
    <a
    href="bpkg-rep-remove.xhtml"><code><b>bpkg-rep-remove(1)</b></code></a>).
    Such a package is called an <i>orphan</i>. Without the
    <code><b>--deorphan</b></code> option, upgrading, downgrading, or patching
    an orphan will leave it unchanged if a more suitable version of the
    package is not available. If the <code><b>--deorphan</b></code> option is
    specified, then an orphan will be replaced with a non-orphan. In this
    case, if <code><b>--upgrade</b></code>, <code><b>--patch</b></code>, or
    the package version is specified, then the new version is selected
    accordingly. Otherwise, the closest version to the orphaned version is
    selected using the following preference order: (1) same version, revision,
    and iteration, (2) latest iteration of same version and revision, (3)
    later revision of same version, (4) later patch of same version, (5) later
    minor of same version, (6) latest available version, including earlier
    (see <a href="build2-package-manager-manual.xhtml#package-version">Package
    Version</a> for details).</p></dd>

    <dt><code><b>--immediate</b></code>|<code><b>-i</b></code></dt>
    <dd>Also upgrade, patch, or deorphan immediate dependencies.</dd>

    <dt><code><b>--recursive</b></code>|<code><b>-r</b></code></dt>
    <dd>Also upgrade, patch, or deorphan all dependencies, recursively.</dd>

    <dt><code><b>--upgrade-immediate</b></code></dt>
    <dd>Upgrade immediate dependencies.</dd>

    <dt><code><b>--patch-immediate</b></code></dt>
    <dd>Patch immediate dependencies.</dd>

    <dt><code><b>--deorphan-immediate</b></code></dt>
    <dd>Deorphan immediate dependencies.</dd>

    <dt><code><b>--upgrade-recursive</b></code></dt>
    <dd>Upgrade all dependencies, recursively.</dd>

    <dt><code><b>--patch-recursive</b></code></dt>
    <dd>Patch all dependencies, recursively.</dd>

    <dt><code><b>--deorphan-recursive</b></code></dt>
    <dd>Deorphan all dependencies, recursively.</dd>

    <dt><code><b>--dependency</b></code></dt>
    <dd>Build, upgrade, or downgrade a package as a dependency rather than to
    hold.</dd>

    <dt><code><b>--keep-out</b></code></dt>
    <dd>Keep output directories of external packages between upgrades and
    downgrades. Refer to <a
    href="bpkg-pkg-disfigure.xhtml"><code><b>bpkg-pkg-disfigure(1)</b></code></a>
    for details.</dd>

    <dt><code><b>--disfigure</b></code></dt>
    <dd>Disfigure packages between upgrades and downgrades effectively causing
    a from-scratch reconfiguration.</dd>

    <dt><code><b>--checkout-root</b></code> <code><i>dir</i></code></dt>
    <dd>Check out packages that come from version control-based repositories
    into the specified directory rather than into the configuration directory.
    Refer to the <code><b>--output-root</b></code> option in <a
    href="bpkg-pkg-checkout.xhtml"><code><b>bpkg-pkg-checkout(1)</b></code></a>
    for details.</dd>

    <dt><code><b>--checkout-purge</b></code></dt>
    <dd>Remove the checked out package (source) directories when the packages
    are purged. Refer to the <code><b>--output-purge</b></code> option in <a
    href="bpkg-pkg-checkout.xhtml"><code><b>bpkg-pkg-checkout(1)</b></code></a>
    for details.</dd>

    <dt><code><b>--config-name</b></code> <code><i>name</i></code></dt>
    <dd>Name of the linked configuration to build this package(s) in. By
    default, the package is built in the current configuration. Repeat this
    option to specify multiple configurations.</dd>

    <dt><code><b>--config-id</b></code> <code><i>num</i></code></dt>
    <dd>Numeric id of the linked configuration to build this package(s) in. By
    default, the package is built in the current configuration. Repeat this
    option to specify multiple configurations.</dd>

    <dt><code><b>--config-uuid</b></code> <code><i>uuid</i></code></dt>
    <dd>UUID of the linked configuration to build this package(s) in. By
    default, the package is built in the current configuration. Repeat this
    this option to specify multiple configurations.</dd>
  </dl>

  <h1>PKG-BUILD GLOBAL OPTIONS</h1>

  <dl class="options">
    <dt><code><b>--yes</b></code>|<code><b>-y</b></code></dt>
    <dd>Assume the answer to all prompts is <code><b>yes</b></code>. Note that
    this excludes the system package manager prompts; see
    <code><b>--sys-yes</b></code> for details.</dd>

    <dt><code><b>--for</b></code>|<code><b>-f</b></code> <code><i>operation</i></code></dt>
    <dd>Instead of the default <code><b>update</b></code> build system
    operation, perform the
    <code><b>update-for-</b></code><code><i>operation</i></code> variant where
    <code><i>operation</i></code> is normally <code><b>install</b></code> or
    <code><b>test</b></code>.</dd>

    <dt><code><b>--keep-unused</b></code>|<code><b>-K</b></code></dt>
    <dd>Don't drop dependency packages that were automatically built but will
    no longer be used.</dd>

    <dt><code><b>--update-dependent</b></code>|<code><b>-U</b></code></dt>
    <dd>Update without confirmation dependent packages that are reconfigured
    due to their dependencies being upgraded or downgraded.</dd>

    <dt><code><b>--leave-dependent</b></code>|<code><b>-L</b></code></dt>
    <dd>Don't offer to update dependent packages that are reconfigured due to
    their dependencies being upgraded or downgraded.</dd>

    <dt><code><b>--configure-only</b></code>|<code><b>-c</b></code></dt>
    <dd>Configure all the packages but don't update.</dd>

    <dt><code><b>--print-only</b></code></dt>
    <dd>Print to <code><b>stdout</b></code> what would be done without
    actually doing anything.</dd>

    <dt><code><b>--plan</b></code> <code><i>header</i></code></dt>
    <dd>Print the plan (even if <code><b>--yes</b></code> is specified) and
    start it with the <code><i>header</i></code> line (unless it is
    empty).</dd>

    <dt><code><b>--no-fetch</b></code></dt>
    <dd>Don't fetch repositories specified as part of the build command.</dd>

    <dt><code><b>--fetch-shallow</b></code></dt>
    <dd>Don't re-fetch complement and prerequisite repositories of
    repositories specified as part of the build command. Refer to the
    <code><b>--shallow</b></code> option in <a
    href="bpkg-rep-fetch.xhtml"><code><b>bpkg-rep-fetch(1)</b></code></a> for
    details.</dd>

    <dt><code><b>--mask-repository</b></code> <code><i>rep</i></code></dt>
    <dd>For the duration of the command execution pretend the specified
    repository was removed as if by performing the
    <code><b>rep-remove</b></code> command. The repository can be specified
    either as a repository name or as a repository location (URL or a
    directory path). Note that the repository's complement and prerequisite
    repositories are also considered masked, recursively, unless they are
    complements and/or prerequisites of other unmasked repositories. Repeat
    this option to mask multiple repositories.</dd>

    <dt><code><b>--mask-repository-uuid</b></code> <code><i>v</i></code></dt>
    <dd>For the duration of the command execution pretend the specified
    repository was removed from the specified configuration. Similar to
    <code><b>--mask-repository</b></code> but only masks the repository in a
    single configuration. The option value is a key-value pair in the form:

    <p class="code"><code><i>config-uuid</i><b>=</b><i>rep</i></code></p>

    <p>Repeat this option to mask multiple repositories.</p></dd>

    <dt><code><b>--no-refinement</b></code></dt>
    <dd>Don't try to refine the configuration by offering to drop any unused
    dependencies that were potentially left behind on the previous
    <code><b>pkg-build</b></code> or <code><b>pkg-drop</b></code> command
    execution if the command is otherwise a noop (performs no new package
    builds, upgrades, etc).</dd>

    <dt><code><b>--no-move</b></code></dt>
    <dd>Don't move dependency packages between configurations. In this mode
    the <code><b>--config-*</b></code> options specify packages' current
    rather than new locations.</dd>

    <dt><code><b>--noop-exit</b></code> <code><i>code</i></code></dt>
    <dd>Exit with the specified error code if the command execution is a noop
    (performs no new package builds, upgrades, etc).</dd>

    <dt><code><b>--rebuild-checksum</b></code> <code><i>sum</i></code></dt>
    <dd>Hash the names, versions, and configurations of all the packages that
    would be built. If the resulting checksum matches the specified, then exit
    without building anything (potentially with a special error code specified
    with the <code><b>--noop-exit</b></code> option). Otherwise, proceed to
    build as normal. In both cases, print the resulting checksum to
    <code><b>stdout</b></code>.</dd>

    <dt><code><b>--no-private-config</b></code> <code><i>code</i></code></dt>
    <dd>If no configuration of a suitable type is linked to build a build-time
    dependency, instead of automatically creating a private configuration of
    this type, exit with the specified error code printing to
    <code><b>stdout</b></code> the dependency chain starting from the
    build-time dependency (together with its constraint, if present) and
    ending with the top-level dependent (together with their configuration
    directories), one entry per line. For example:

    <pre>yacc ^1.0.0
libbar/1.0.0 /path/to/libbar/cfg/
libfoo/1.0.0 /path/to/libfoo/cfg/</pre>

    <p>See <a
    href="bpkg-cfg-create.xhtml"><code><b>bpkg-cfg-create(1)</b></code></a>
    for details on linked configurations.</p></dd>

    <dt><code><b>--sys-no-query</b></code></dt>
    <dd>Do not query the system package manager for the installed versions of
    packages specified with the <code><b>sys</b></code> scheme.</dd>

    <dt><code><b>--sys-install</b></code></dt>
    <dd>Instruct the system package manager to install available versions of
    packages specified with the <code><b>sys</b></code> scheme that are not
    already installed. See also the <code><b>--sys-no-fetch</b></code>,
    <code><b>--sys-yes</b></code>, and <code><b>--sys-sudo</b></code>
    options.</dd>

    <dt><code><b>--sys-no-fetch</b></code></dt>
    <dd>Do not fetch the system package manager metadata before querying for
    available versions of packages specified with the <code><b>sys</b></code>
    scheme. This option only makes sense together with
    <code><b>--sys-install</b></code>.</dd>

    <dt><code><b>--sys-no-stub</b></code></dt>
    <dd>Do no require a stub for packages specified with the
    <code><b>sys</b></code> scheme. Note that this option has effect only if
    the system package manager interactions are supported and not
    disabled.</dd>

    <dt><code><b>--sys-yes</b></code></dt>
    <dd>Assume the answer to the system package manager prompts is
    <code><b>yes</b></code>. Note that system package manager interactions may
    break your system and you should normally only use this option on
    throw-away setups (test virtual machines, etc).</dd>

    <dt><code><b>--sys-sudo</b></code> <code><i>prog</i></code></dt>
    <dd>The <code><b>sudo</b></code> program to use for system package manager
    interactions that normally require administrative privileges (fetch
    package metadata, install packages, etc). If unspecified,
    <code><b>sudo</b></code> is used by default. Pass empty or the special
    <code><b>false</b></code> value to disable the use of the
    <code><b>sudo</b></code> program. Note that the <code><b>sudo</b></code>
    program is normally only needed if the system package installation is
    enabled with the <code><b>--sys-install</b></code> option.</dd>

    <dt><code><b>--sys-distribution</b></code> <code><i>name</i></code></dt>
    <dd>Alternative system/distribution package manager to interact with. The
    valid <code><i>name</i></code> values are <code><b>debian</b></code>
    (Debian and alike, such as Ubuntu, etc) and <code><b>fedora</b></code>
    (Fedora and alike, such as RHEL, CentOS, etc). Note that some package
    managers may only be supported when running on certain host operating
    systems.</dd>

    <dt><code><b>--sys-architecture</b></code> <code><i>name</i></code></dt>
    <dd>Alternative architecture to use when interacting with the system
    package manager. The valid <code><i>name</i></code> values are
    system/distribution package manager-specific. If unspecified, the host
    architecture is used.</dd>

    <dt><code><b>--directory</b></code>|<code><b>-d</b></code> <code><i>dir</i></code></dt>
    <dd>Assume current configuration is in <code><i>dir</i></code> rather than
    in the current working directory. Repeat this option to specify multiple
    current configurations. If multiple configurations are specified, they
    need not belong to the same linked configuration cluster.</dd>
  </dl>

  <h1>COMMON OPTIONS</h1>

  <p>The common options are summarized below with a more detailed description
  available in <a
  href="bpkg-common-options.xhtml"><code><b>bpkg-common-options(1)</b></code></a>.</p>

  <dl class="options">
    <dt><code><b>-v</b></code></dt>
    <dd>Print essential underlying commands being executed.</dd>

    <dt><code><b>-V</b></code></dt>
    <dd>Print all underlying commands being executed.</dd>

    <dt><code><b>--quiet</b></code>|<code><b>-q</b></code></dt>
    <dd>Run quietly, only printing error messages.</dd>

    <dt><code><b>--verbose</b></code> <code><i>level</i></code></dt>
    <dd>Set the diagnostics verbosity to <code><i>level</i></code> between 0
    and 6.</dd>

    <dt><code><b>--stdout-format</b></code> <code><i>format</i></code></dt>
    <dd>Representation format to use for printing to
    <code><b>stdout</b></code>.</dd>

    <dt><code><b>--jobs</b></code>|<code><b>-j</b></code> <code><i>num</i></code></dt>
    <dd>Number of jobs to perform in parallel.</dd>

    <dt><code><b>--no-result</b></code></dt>
    <dd>Don't print informational messages about the outcome of performing a
    command or some of its parts.</dd>

    <dt><code><b>--structured-result</b></code> <code><i>fmt</i></code></dt>
    <dd>Write the result of performing a command in a structured form.</dd>

    <dt><code><b>--progress</b></code></dt>
    <dd>Display progress indicators for long-lasting operations, such as
    network transfers, building, etc.</dd>

    <dt><code><b>--no-progress</b></code></dt>
    <dd>Suppress progress indicators for long-lasting operations, such as
    network transfers, building, etc.</dd>

    <dt><code><b>--diag-color</b></code></dt>
    <dd>Use color in diagnostics.</dd>

    <dt><code><b>--no-diag-color</b></code></dt>
    <dd>Don't use color in diagnostics.</dd>

    <dt><code><b>--build</b></code> <code><i>path</i></code></dt>
    <dd>The build program to be used to build packages.</dd>

    <dt><code><b>--build-option</b></code> <code><i>opt</i></code></dt>
    <dd>Additional option to be passed to the build program.</dd>

    <dt><code><b>--fetch</b></code> <code><i>path</i></code></dt>
    <dd>The fetch program to be used to download resources.</dd>

    <dt><code><b>--fetch-option</b></code> <code><i>opt</i></code></dt>
    <dd>Additional option to be passed to the fetch program.</dd>

    <dt><code><b>--fetch-timeout</b></code> <code><i>sec</i></code></dt>
    <dd>The fetch and fetch-like (for example, <code><b>git</b></code>)
    program timeout.</dd>

    <dt><code><b>--pkg-proxy</b></code> <code><i>url</i></code></dt>
    <dd>HTTP proxy server to use when fetching package manifests and archives
    from remote <code><b>pkg</b></code> repositories.</dd>

    <dt><code><b>--git</b></code> <code><i>path</i></code></dt>
    <dd>The git program to be used to fetch git repositories.</dd>

    <dt><code><b>--git-option</b></code> <code><i>opt</i></code></dt>
    <dd>Additional common option to be passed to the git program.</dd>

    <dt><code><b>--sha256</b></code> <code><i>path</i></code></dt>
    <dd>The sha256 program to be used to calculate SHA256 sums.</dd>

    <dt><code><b>--sha256-option</b></code> <code><i>opt</i></code></dt>
    <dd>Additional option to be passed to the sha256 program.</dd>

    <dt><code><b>--tar</b></code> <code><i>path</i></code></dt>
    <dd>The tar program to be used to extract package archives.</dd>

    <dt><code><b>--tar-option</b></code> <code><i>opt</i></code></dt>
    <dd>Additional option to be passed to the tar program.</dd>

    <dt><code><b>--openssl</b></code> <code><i>path</i></code></dt>
    <dd>The openssl program to be used for crypto operations.</dd>

    <dt><code><b>--openssl-option</b></code> <code><i>opt</i></code></dt>
    <dd>Additional option to be passed to the openssl program.</dd>

    <dt><code><b>--auth</b></code> <code><i>type</i></code></dt>
    <dd>Types of repositories to authenticate.</dd>

    <dt><code><b>--trust</b></code> <code><i>fingerprint</i></code></dt>
    <dd>Trust repository certificate with a SHA256
    <code><i>fingerprint</i></code>.</dd>

    <dt><code><b>--trust-yes</b></code></dt>
    <dd>Assume the answer to all authentication prompts is
    <code><b>yes</b></code>.</dd>

    <dt><code><b>--trust-no</b></code></dt>
    <dd>Assume the answer to all authentication prompts is
    <code><b>no</b></code>.</dd>

    <dt><code><b>--git-capabilities</b></code> <code><i>up</i></code>=<code><i>pc</i></code></dt>
    <dd>Protocol capabilities (<code><i>pc</i></code>) for a
    <code><b>git</b></code> repository URL prefix
    (<code><i>up</i></code>).</dd>

    <dt><code><b>--pager</b></code> <code><i>path</i></code></dt>
    <dd>The pager program to be used to show long text.</dd>

    <dt><code><b>--pager-option</b></code> <code><i>opt</i></code></dt>
    <dd>Additional option to be passed to the pager program.</dd>

    <dt><code><b>--options-file</b></code> <code><i>file</i></code></dt>
    <dd>Read additional options from <code><i>file</i></code>.</dd>

    <dt><code><b>--default-options</b></code> <code><i>dir</i></code></dt>
    <dd>The directory to load additional default options files from.</dd>

    <dt><code><b>--no-default-options</b></code></dt>
    <dd>Don't load default options files.</dd>

    <dt><code><b>--keep-tmp</b></code></dt>
    <dd>Don't remove the <code><b>bpkg</b></code>'s temporary directory at the
    end of the command execution and print its path at the verbosity level 2
    or higher.</dd>
  </dl>

  <h1>DEFAULT OPTIONS FILES</h1>

  <p>See <a
  href="bpkg-default-options-files.xhtml"><code><b>bpkg-default-options-files(1)</b></code></a>
  for an overview of the default options files. For the
  <code><b>pkg-build</b></code> command the search start directory is the
  configuration directory. The following options files are searched for in
  each directory and, if found, loaded in the order listed:</p>

  <pre>bpkg.options
bpkg-pkg-build.options</pre>

  <p>The following <code><b>pkg-build</b></code> command options cannot be
  specified in the default options files:</p>

  <pre>--directory|-d</pre>

  <h1>BUGS</h1>

  <p>Send bug reports to the
  <a href="mailto:users@build2.org">users@build2.org</a> mailing list.</p>

</div>

<div id="footer">
Copyright &#169; 2014-2024 the build2 authors.<br/>
Permission is granted to copy, distribute and/or modify this document under
the terms of the MIT License.
</div>

</body>
</html>
